Release 10.1A: OpenEdge Development:
Programming Interfaces

Managing and transporting crypto data

Crypto data consists of all the information required to maintain secure data. This includes the source data, typically in clear-text form; the encrypted or hashed data; all passwords, key values, and algorithms; and all platform parameters required to maintain the data, such as code pages for character strings and the byte endian order for binary values.

This section describes some of the basic objectives and requirements for managing crypto data in the 4GL. For more information on the larger and more complex factors that you need to consider when using cryptography, see the Security whitepaper prepared by Progress Marketing, which can be found on the PSDN Web site.

Caution: Managing crypto data incorrectly can result in the loss of your original source data. You must ensure that all interactions with this data are both safe and secure.

Objectives for crypto data management

The main objectives for managing and transporting crypto data is the same for all types of encryption and data:

To ensure that the required level of security is maintained as data is moved and stored.
To ensure that secured data can always be recovered by those who are authorized to recover it.

Requirements for crypto data management

The requirements for managing and transporting crypto data depend upon the:

Type of cryptography — In the 4GL, this can include symmetric cryptography, message digests, and key generation.
Media for storage or transport — This can include static media, such as databases and external files and dynamic media, such as session memory and network connections.

One general requirement for managing encrypted or digested data is to be certain that all keys once generated, are recoverable. For example, if you use the GENERATE-RANDOM-KEY function to set a symmetric key and you use this function to directly set the SYMMETRIC-ENCRYPTION-KEY attribute of the SECURITY-POLICY system handle, the key value that you set is non-recoverable because the SYMMETRIC-ENCRYPTION-KEY attribute is write-only. If you encrypt data using this setting, you can never decrypt it after the 4GL session in which you encrypt the data has ended. Therefore, to correctly use the GENERATE-RANDOM-KEY function for symmetric encryption, you must set and maintain the value of a readable variable using this function and then set the SYMMETRIC-ENCRYPTION-KEY attribute using this variable. Of course, you must also ensure that you immediately save the key value in a secure location and erase the value in memory in order to both secure your current 4GL session and safely recover the key value at a later time to decrypt whatever data you have encrypted with it.

Crypto data storage

If you use external files to store crypto keys, passwords, and data make certain that you use secure operating system files to do it.

If you use a database to store crypto data, be sure to secure any keys or passwords that you store in the database separately from the data that you have encrypted.

Caution: Never encrypt a password required to access encrypted data using the same password-based encryption (PBE) key used to encrypt the data. Always manage the password separately from the data that you intend to encrypt with it, and always manage the password separately from any salt that you combine with the password to generate the PBE key.

Crypto data management and transport

When you store or transport crypto data, you can do it in two basic forms:

Binary byte stream — Accessible through a 4GL MEMPTR or RAW variable. This the native form in which key values and encrypted or hashed data are generated. The primary requirement for binary data is that you maintain byte-endian order for all hardware platforms where you transport the data. You can help to ensure this by using the GET-BYTE and PUT-BYTE functions to read and write the data instead of GET-LONG and PUT-LONG. You can also convert a binary data string into a string of hexadecimal character pairs using the 4GL built-in HEX-ENCODE function, transport it to a different hardware platform, and convert hexadecimal character string back to binary on that platform using the 4GL built-in HEX-DECODE function.
Base64-encoded character string — Accessible through a 4GL CHARACTER or LONGCHAR variable. You can convert binary data into this form using the 4GL built-in BASE64-ENCODE function and convert it back to binary using the 4GL built-in BASE64-DECODE function. The primary requirement for Base64-encoded and encrypted data is that you remember to decode it from Base64 before you decrypt the data.

Caution: If encrypted data is not in the correct byte order or format, the DECRYPT function has no way of knowing this and will successfully “decrypt” the data to an invalid value.

If you store encrypted data in a database:

Do not use it for searches or indexes unless duplicates are allowed, as there is no way to know that two different pieces of data have been encrypted to the same value.
Plan for changes in the size of database items that you store in both clear text and encrypted form. Both encryption and Base64-encoding increase the size of stored data.

Caution: If you encrypt data in a database, other applications that use the database, such as Crystal Reports, might not work as you want.

Planning for changes in size for encrypted data

Data size increases at two points:

During symmetric encryption, using the 4GL ENCRYPT function.
During conversion from a binary byte stream to a Base64-encoded string, using the 4GL BASE64-ENCODE function.

The formula for change in data size during symmetric encryption is:

ems = (((ums / 8) + 1) * 8)

In this formula:

ems is the encrypted maximum size.
ums is the unencrypted maximum size.

The formula for change in data size when Base64-encoding a binary byte stream is:

ems = (((bms / 8) + 1) * 8)

ems is the Base64-encoded maximum size.
bms is the binary maximum size, which is equal to the encrypted maximum size of the data that has been encrypted using the DECRYPT function.

This increase in size from binary to Base64-encoding is generally 33%. So, encrypted data in a RAW or MEMPTR variable becomes 33% larger after you convert to a Base64-encoded CHARACTER or LONGCHAR variable.